3D Graphics Programming with QuickDraw 3D 1.5.4

Application-Defined Routines

QuickDraw 3D allows you to specify idle methods that QuickDraw 3D can call occasionally during lengthy operations. Two tools, TQ3ViewIdleProgressMethod and TQ3ViewEndFrameMethod, provide progress and end-of-frame information. They can be called only from a renderer plug-in module.

TQ3ViewIdleMethod

You can define an idle method to receive occasional callbacks to your application during lengthy operations.



 
typedef TQ3Status (*TQ3ViewIdleMethod) (

                     TQ3ViewObject view, 

                     const void *idleData);

view: A view.
idleData: A pointer to an application-defined block of data.

DESCRIPTION

Your TQ3ViewIdleMethod function is called occasionally during lengthy operations, such as rendering a complex model. You can use an idle method to provide a means for the user to cancel the lengthy operation (for example, by clicking a button or pressing a key sequence such as Command-period).

If your idle method returns kQ3Success , QuickDraw 3D continues its current operation. If your idle method returns kQ3Failure , QuickDraw 3D cancels its current operation and returns kQ3ViewStatusCancelled the next time you call Q3View_EndRendering or a similar function. You should not call Q3View_Cancel (or any other QuickDraw 3D routine) inside your idle method.

There is currently no way to indicate how often you want your idle method to be called. You can read the time maintained by the Operating System if you need to determine the amount of time that has elapsed since your idle method was last called.

SPECIAL CONSIDERATIONS

You must not call any QuickDraw 3D routines inside your idle method. In particular, you must not change any of the settings of the view being rendered or call Q3View_StartRendering on that same view.

Some renderers (particularly those that use hardware accelerators) might not support idle methods.

TQ3ViewIdleProgressMethod

You can use the TQ3ViewIdleProgressMethod function to to register callback routines that the view can call during long operations. It helps provide data for a user interface indicator showing progress, and may also be used to interrupt long renderings or traversals. Within the idler callback code, the application can check for a cancel button or command key combination that lets the user interrupt rendering.

TQ3ViewIdleProgressMethod can be called only from a renderer plug-in module.



 
TQ3Status Q3View_SetIdleProgressMethod(

                     TQ3ViewObject view,

                     TQ3ViewIdleProgressMethod idleMethod,

                     const void *idleData);

view: A view.
idleMethod: An idle method (see below).
idleData: A pointer to an application-defined block of data.



 
typedef TQ3Status (*TQ3ViewIdleProgressMethod)(

                     TQ3ViewObject    view,

                     const void       *idlerData,

                     unsigned long    current,

                     unsigned long    completed);

view: A view.
idlerData: A pointer to an application-defined block of data. This pointer is passed to the idle method when it is executed.
current: Numerator of progress fraction. Its value is always less than the value of completed.
completed: Denominator of progress fraction. The value of current/completed gives the degree of completion.

DESCRIPTION

TQ3ViewIdleProgressMethod registers a callback that also returns progress information. This information is supplied by the renderer, and may or may not be based on real time. If a renderer doesn't support the progress method, your method will be called with current and completed both set to 0. Otherwise, you are certain to get called at least twice:

once idleMethod(view, 0, n) Initialize, show dialog
0 or more times idleMethod(view, 1..n-1, n) Update progress
once idleMethod(view, n, n) Exit, hide dialog

There is no way to set timer intervals when you want to be called--it is up to the application's idler callback to check clock times to see how long ago the application was called. TQ3ViewIdleProgressMethod returns kQ3Failure to cancel rendering, kQ3Success to continue. It does not post errors.

SPECIAL CONSIDERATIONS

Because your callback function may be called at hardware interrupt level, be careful about using Macintosh Toolbox routines. To call the Toolbox, you may want to set a global variable that you can later poll at noninterrupt level.

It is not legal to call QD3D routines inside an idler callback.

TQ3ViewEndFrameMethod

You can use the TQ3ViewEndFrameMethod function to determine when an asynchronous renderer has completed rendering a frame.

TQ3ViewEndFrameMethod can be called only from a renderer plug-in module.



 
TQ3Status Q3View_SetEndFrameMethod(

                     TQ3ViewObject view,

                     TQ3ViewEndFrameMethod endFrame,

                     void *endFrameData);

view: A view.
endFrame: An end-of-frame method (see below).
endFrameData: A pointer to an application-defined block of data.



 
typedef void (*TQ3ViewEndFrameMethod)(

                     TQ3ViewObject view,

                     void *endFrameData);

view: A view.
endFrameData: A pointer to an application-defined block of data.

DESCRIPTION

TQ3ViewEndFrameMethod provides an alternative to Q3View_Sync for determining when an asynchronous renderer has completed rendering a frame. With Q3View_Sync , the application asks a renderer to finish rendering a frame and blocks until the frame is complete. With TQ3ViewEndFrameMethod, the renderer tells the application that it has completed a frame.

If Q3View_Sync is called before TQ3ViewEndFrameMethod has been called, TQ3ViewEndFrameMethod will never be called. If Q3View_Sync is called after TQ3ViewEndFrameMethod has been called, Q3View_Sync will return immediately because the frame has already been completed.